前言

其實一直很猶豫要不要寫這篇，因為 UI Framework 最終還是要從官方文件去看使用方式。
但又想起當初，自己一開始使用 Quasar 的時候，進入官網那種迷失的感覺XD，常常找不到東西在哪裡，也看不懂元件文件（可能因為太菜...），所以...我想還是有一些資訊可以先提供給初入 Quasar 的 Vue 3 新手。

所以今天這篇的目標是：幫助第一次使用 Quasar 的人，快速認識 Quasar 提供的功能，還有讀懂 Quasar 的元件文件。

Outline

• Quasar
  • 安裝
  • 引入
  • 官網分類地圖
• 使用 Quasar 元件
• 修改 UI framework 元件樣式 feat: :deep()

Quasar

Quasar 是一套基於 vue.js 開發的強大 UI framework，就像積木一樣，把所有元件素材都提供給開發者，讓開發者可以組裝出自己需要的元件。

先前已經使用 Vue 官方的 Project Scaffolding 建立專案，所以這次選擇的是「Vite plugin for Quasar」，將 Quasar 插件安裝到現成的 Vue + Vite 專案上。

而 Quasar CLI 是 Quasar 提供的 Project Scaffolding，可以快速建立使用 Quasar 的 Vue 專案，會協助安裝開發所需的工具：CSS 預處理器、Vite/Vue CLI、ESLint、狀態管理器（Pinia/Vuex）、axios 和 Vue-i118n，指令為 npm init quasar。

註：Vite plugin 的形式不支援 SSR，SSR 專案建議使用 Quasar CLI with Vite。

安裝

npm install quasar @quasar/extras
npm install -D @quasar/vite-plugin sass@1.32.12

yarn add quasar @quasar/extras
yarn add -D @quasar/vite-plugin sass@1.32.12

• quasar 一定要安裝
• @quasar/extras Optional，主要支援 icon 和動畫（Animate.css），包含 Google 的 Material Icons、Font Awesome、Bootstrap Icons 等等，可以在這裡 看到可取引用的列表。
• sass@1.32.12 欲使用 Quasar Sass/SCSS 變數應安裝

引入

Quasar 官網上可以根據專案需求，產生引入和 config 檔案（也就是 main.js 和 vite.config.js 的部份）

• 是否引入 Roboto font / Roboto font extended（支援拉丁文） / Animations from Animate.css
• 選擇要引入的 Icon library
• Auto-Import Component Case：在 Vue 模板使用 Quasar 元件的命名規則，預設為 "kebab"（<q-btn>）
• 是否引入 Quasar Sass/SCSS 變數
• 是否留下 Quasar Config Object 空物件位置（見底下程式碼）
• Quasar Icon Set：預設使用的 Icon library

myApp.use(Quasar, {
  plugins: {},
  /* ～～Quasar Config Object～～
  config: {
    brand: {
      // primary: '#e46262',
      // ... other brand colors
    },
    notify: {...}, // default set of options for Notify Quasar plugin
    loading: {...}, // default set of options for Loading Quasar plugin
    loadingBar: { ... }, // settings for LoadingBar Quasar plugin
  }
  */
})

將產生的程式碼貼到 main.js 和 vite.config.js 內，就可以輕鬆使用 Quasar。

官網分類地圖

常用分類

• Options & Helper：
  • 有各種哩哩摳摳的東西(心虛XD)
  • 包含 Screen plugin、Transition 和 Animation 等等
• Style & Idendity：通用的 Style Utilities，包含：顏色、大小和間距等等
• Layout and Grid：
  • 網格系統，如：.row、.col
  • QLayout，可以搭配 Layout Builder 使用，快速建立具 RWD 效果的頁面基本架構（
• Vue Component：各種立即可用的 Quasar Vue 元件
• Vue Directive：Quasar 自訂的 Vue 指令，常搭配 Component 使用，在使用 component 的時候可以看到
• Vue Composable：Quasar 提供的 Composable 函式

使用 Quasar 元件

在安裝和引入都設定好後，就可以直接在模板使用 Quasar 元件，不需要在個別 .vue 檔引入其他東西。

<template>
  <QInput />
</template>

注意：autoImportComponentCase 預設值為 kebab，我自己習慣使用 pascal（大駝峰），所以引入 Quasar 元件都是使用大駝峰的命名方式。

讓我們用 QInput 來示範！

• 上側欄位是定義好和 Quasar 元件互動的方式
• 左側欄位是 Quasar 根據性質進行分類

QInput 就是 Quasar 幫我們包好的 Input 元件，裡面已經定義好 prop、emit、slot，需要根據這些規則去調整元件的樣式或功能。

props、emit

• props：元件接受的 props 屬性一覽。
• event：元件會 emit 的事件一覽。

以如何取值為例

在 QInput 的元件上可以看到：

• 有 prop 名稱為 model-value
• 有 event 事件為 @update:model-value -> function(value)
  • function(value) 表示 handler 可以接到一個 value 參數，為更新的 value 值

這兩項合起來其實就是 v-model 搭配元件的用法，所以要雙向綁定 QInput 的值有兩種寫法：

<template>
  <QInput ref="qInput" v-model="name" />
  <QInput
    ref="qInput"
    :model-value="name"
    @update:model-value="(newValue) => (name = newValue)"
  />
  <p>{{ name }}</p>
</template>

slots

元件預先留的 named slot 或 default slot 區塊。

以 QInput 為例，Quasar 預留了 10 個 slot 位置，可以自訂模板塞入這些區塊，可以搭 Quasar 的 ICon 等等，以下圖示範 before、prepend、label、append 和 after 的位置：

實際運用案例：

Method & Computed

比較特別的是，部份 Quasar 元件內部會有定義好的 method 和 computed，那我們要怎麼拿來用呢？

我們可以透過 ref 屬性，取得 QInput 的元件實例，從元件實例（物件型別）中，可以取到內部的 method 和 computed 屬性。

以 QInput 為例，Quasar 有定義一個 method 為 focus () => void 0 和一個 computed 屬性為hasError。

<template>
  <QInput ref="qInput" v-model="name"/>
</template>

import { onMounted, ref } from "vue";
const qInput = ref(null);
const name = ref("");

// 加上這行會報錯，因為元件還沒掛載上去，qInput 還是 `null`
console.log(qInput.value.focus);

// 等到完成掛載，就能取到元件實例下的屬性
onMounted(() => console.log(qInput.value.focus));
onMounted(() => console.log(qInput.value.hasError));

// 等到元件掛載完成，呼叫 quasar 元件的方法來 focus 輸入框
onMounted(() => qInput.value.focu());

小複習：ref 特殊屬性

• 綁定原生元素可以取得 DOM，綁定元件可以取得元件實例
• 元件/元素的 ref 綁定名稱，需要和 script 宣告的變數同名，就可以在 script 取得元件實例或 DOM
• 要等到元件掛載上去，才可以在父層取到元件實例

修改 UI framework 元件樣式

使用自己包的元件時，樣式通常會很符合專案的風格，比較不需要在引用時去調整元件的樣式。

但使用 UI framework 的元件時，到底該怎麼改，才不會影響到全部引用的元件呢？

template 架構

<QInput v-model="name" label="姓名" />

渲染結果

目標：把 label（姓名）的顏色改成紅色！

先開 devtool 看要蓋的樣式選擇器是什麼

1. <style> 不加 scoped：
   • 可以影響 label 標籤字體顏色，但是全部的 Input label 都會變成紅色
   • 如果是刻意想影響專案內所有 Input 的 label 顏色，那這個方法是可以的，但不推薦，因為無法確定 Quasar 在哪些元件上用了相同的 class

<style>
.q-field__label {
  color: #e74c3c;
}
</style>

2. <style scoped>：
   • 只想影響後代 label 標籤字體顏色，需要搭配 :deep() 選擇器

<style scoped>
:deep(.q-field__label) {
  color: #e74c3c;
}
</style>

小結

Quasar 的元件內建各～種～功能和樣式提供開發者做選擇，沒辦法一次看完全部，要在開發時善用關鍵字搜尋。通常，你想要的功能 Quasar 都有，只是有沒有找到說明的地方而已哈哈。
一開始對 Quasar 元件文件還不熟悉的時候，會覺得用得很不順手，等到熟悉之後，就會發現 Quasar 真的很好用，好用到自我懷疑...懷疑自己究竟能不能實作出 Quasar 元件的某些功能 QQ

今天先到這裡，30 天竟然快結束了，好猶豫明天最後要寫什麼呀...